Debug User-Node Mapping Issues

This guide helps you debug issues where a device (node) is not getting associated with a user account in ESP RainMaker. This covers problems during provisioning (device not appearing in the app), mapping request timeouts, and node sharing failures.

Before you start, have these ready:

• Node ID of the affected device
• User ID or email of the affected user
• Approximate time when the issue occurred

---

Step 1: Check What Symptom You Are Seeing

Choose the section that matches your issue:

Symptom	Go to
Device provisioned but not showing in the app	Device Not Appearing After Provisioning
App shows "Node addition not confirmed" or times out	Mapping Request Timed Out
Device is in the app but not responding to commands	Mapping Confirmed but Device Not Responding
Error when sharing a node with another user	Node Sharing Failed
Getting a specific error code (103xxx / 107xxx)	Error Code Reference

---

Device Not Appearing After Provisioning

Step 1: Check If the Mapping Was Confirmed

Go to AWS Console → DynamoDB → Tables → user_node_mapping.

Click Explore items and query with:

• Partition key (user_id): the user's Cognito user ID
• Sort key (node_id): the node ID

What you find:

• Entry exists with status = "active" → The mapping is confirmed. The device is associated. Skip to Mapping Confirmed but Device Not Responding.
• No entry found → The mapping was never completed. Continue to Step 2.

tip

If you don't have the user_id, you can query by node_id using the GSI index user_node_mapping_node_id_all_index — select Query and switch the index in the dropdown.

Step 2: Check the Mapping Request Status

Go to AWS Console → DynamoDB → Tables → user_node_mapping_requests.

Query with partition key (user_node_id): <user_id>_<node_id>

What you find and what it means:

request_status	What Happened	Next Step
confirmed	Mapping succeeded but user_node_mapping entry is missing — likely a DynamoDB write failure	Check CloudWatch logs (Step 3)
timedout	Either the device or the app sent the mapping request, but the other side did not respond within 1 minute	See Mapping Request Timed Out
discarded	A new request replaced this one — usually a secret key mismatch between app and device	Re-provision the device
failed	Challenge-response signature verification failed	See error 103041 in Error Code Reference
No entry found	The app did not successfully call the mapping API, or the entry already expired (auto-deleted after 7 days)	Check Step 3 for app-side logs

Step 3: Check CloudWatch Logs

Open CloudWatch → Logs Insights. Select both log groups:

• /aws/lambda/esp-UserNodeMapping
• /aws/lambda/esp-LambdaUserNodeMapping

Run this query (replace <node_id> with the actual node ID):

fields @timestamp, @message
| sort @timestamp asc
| filter @message like "<node_id>"

Set the time range to cover when the provisioning attempt happened.

What to look for:

• Entry only in esp-UserNodeMapping (no entry in esp-LambdaUserNodeMapping) → The app called the cloud API successfully, but the device never published its MQTT mapping message. The device did not connect to the cloud or the provisioning data (user_id + secret_key) was not delivered to the device over BLE/SoftAP.
• Entry only in esp-LambdaUserNodeMapping (no entry in esp-UserNodeMapping) → The device sent the mapping MQTT message but the app API call failed. Check app internet connectivity.
• Both entries present but no "confirmed" → Entries were created but keys did not match. This is a secret key mismatch — re-provision the device.
• Error messages in the logs → Note the error code and refer to the Error Code Reference.

Step 4: Check Device Connectivity

If the device never published its MQTT mapping message, verify the device is actually connected to the cloud.

Go to CloudWatch → Logs Insights, select /aws/lambda/esp-ConnectionNode, and run:

fields @timestamp, @message
| sort @timestamp desc
| filter @message like "<node_id>"

• If there are no recent connection events, the device is not connected to the cloud. The device must be connected to the internet and have valid MQTT certificates before mapping can succeed.
• Refer to Debugging Node Connection Issues to resolve connectivity problems first.

---

Mapping Request Timed Out

This happens when one side (the app or the device) sent the mapping request but the other side did not respond with the matching secret key within 1 minute (the default timeout).

Step 1: Identify Which Side Timed Out

Go to DynamoDB → Tables → user_node_mapping_requests and look at the request_source field for the timed-out entry:

request_source	Meaning
"user"	The app sent the request first. The device never published its MQTT mapping message in time.
"node"	The device sent the MQTT message first. The app API call was late or never happened.

Step 2: If request_source is "user" (Device Didn't Respond in Time)

The most common cause. Check these in order:

1. Was the device connected to Wi-Fi when provisioning completed? The device can only publish the MQTT mapping message after it connects to Wi-Fi and establishes an MQTT connection to the cloud. If Wi-Fi connection was slow, the MQTT publish may have happened after the 1-minute window.

2. Check if the MQTT mapping message was published late: In CloudWatch Logs Insights, select /aws/lambda/esp-LambdaUserNodeMapping and search by <node_id>. If there is a log entry but it appeared more than 1 minute after the app's request was created, the mapping timed out due to latency.

3. Check device MQTT connectivity: Go to CloudWatch → /aws/lambda/esp-ConnectionNode and filter by <node_id>. If there is no connection event near the provisioning time, the device failed to connect to the cloud.

4. Check AWS IoT Rule esp_user_node_mapping: If the device is connected and publishes the message but there is no entry in /aws/lambda/esp-LambdaUserNodeMapping, the IoT rule may not be configured. Verify the rule exists in AWS IoT Core → Message routing → Rules.

Fix: Re-provision the device. Ensure the device has a stable internet connection before starting provisioning.

Step 3: If request_source is "node" (App Didn't Respond in Time)

1. Check if the app's API call was made: In CloudWatch → /aws/lambda/esp-UserNodeMapping, search by <node_id>. If there is no log entry, the app never called the mapping API.

2. Check app internet connectivity: The mobile app must have internet access to call https://api.rainmaker.espressif.com. If the phone switched to a different Wi-Fi or lost connectivity during provisioning, the API call would fail.

3. Check if the BLE/SoftAP session dropped: If the connection between the phone and device dropped before the cloud_user_assoc step completed, the app may not have received the confirmation needed to proceed with the API call.

Fix: Re-provision the device with the phone connected to a stable internet connection.

---

Mapping Confirmed but Device Not Responding

If the mapping shows "confirmed" in DynamoDB and the device appears in the app, but the device is not accepting commands or reporting state, the issue is on the device side.

Step 1: Verify the Device Received the MQTT PUBACK

After the device publishes the mapping MQTT message, it waits for an MQTT acknowledgment (PUBACK) from AWS IoT Core. Until it receives this, the device will not subscribe to any parameters and will not respond to commands.

Check in AWS IoT Core → MQTT test client: subscribe to node/<node_id>/user/mapping and check if the device is publishing. If you see a publish but the device still doesn't respond, check IoT Core for errors.

Step 2: Check for MQTT Connection Issues

In CloudWatch → /aws/lambda/esp-ConnectionNode, search for the node ID and look for any DISCONNECT or AUTH_ERROR events around the time of provisioning. If the MQTT connection dropped after the device published but before receiving the PUBACK, the device firmware will be stuck in REQ_SENT state and will not function.

Fix: Factory reset the device and re-provision. The device will restart the mapping process from the beginning.

Step 3: Check if Firmware Re-Flashing Reset the Mapping

If the device firmware was re-flashed after the original mapping, the device automatically sends a reset mapping signal at boot. This revokes the previous user's mapping, requiring re-provisioning.

To confirm: in CloudWatch → /aws/lambda/esp-LambdaUserNodeMapping, filter by <node_id> and look for a reset: true message after the confirmed mapping.

Fix: Re-provision the device to create a fresh mapping.

---

Node Sharing Failed

Step 1: Verify the Target User Exists

Before sharing can succeed, the user you are sharing with must have a CONFIRMED account in Cognito.

1. Go to AWS Console → Cognito → User pools.
2. Open rainmaker-user-pool or rainmaker-user-email-mobile-pool.
3. Search for the target user by email.
4. Check the Confirmation status — it must be CONFIRMED. See Debugging User Connection Issues for details on other statuses.

If the user does not exist or is not confirmed, the sharing request will fail with error 107007.

Step 2: Verify the Sharing Request in DynamoDB

Go to DynamoDB → Tables → user_node_sharing_request and query by the primary user's ID. Look for the sharing request and check its status:

Status	Meaning
pending	Request sent, waiting for the secondary user to accept
accepted	Sharing is active — if node still not visible, check user_node_mapping for the secondary user
declined	Secondary user declined. Send a new request.
cancelled	Request was cancelled by the primary user

Step 3: Check Sharing Logs in CloudWatch

Go to CloudWatch → Logs Insights, select /aws/lambda/esp-UserNodeSharing, and run:

fields @timestamp, @message
| sort @timestamp desc
| filter @message like "<user_email_or_node_id>"

Look for error codes starting with 107 in the log messages and refer to the Error Code Reference below.

Common sharing issues:

Error / Symptom	Cause	Fix
Error 107005	Attempting to share a node you don't own as primary	Verify the requesting user is the "primary" owner in user_node_mapping
Error 107007	Target user email is wrong or unregistered	Verify the email and check Cognito
Error 107014	Trying to remove a node shared via a group	Remove the node from the group first, then remove the share
Error 107003	User trying to share with themselves	Use a different target user email

---

Error Code Reference

Mapping Errors (103xxx)

Error Code	Message	Likely Cause
103003	Invalid operation specified	Operation value must be add or remove
103004	Secret key is blank	The secret key was not included in the request
103005	NodeId is too long	Node ID exceeds 64 characters
103006	Secret key is too long	Secret key exceeds 64 characters
103011	Mapping request timed out	Device did not respond within the timeout window (default: 1 min)
103013	User-node mapping does not exist	Trying to remove a mapping that doesn't exist
103018	Mapping request not found	The request_id provided is invalid or expired
103041	Invalid challenge response	Device's signature did not match the challenge — check device certificate in AWS IoT Core
103043	Request is already confirmed	The request was already processed; no action needed
103044	Request timed out / failed / discarded	This request cannot be confirmed; start a new provisioning attempt

Sharing Errors (107xxx)

Error Code	Message	Likely Cause
107001	Please specify at least one node	No node IDs provided in the sharing request
107002	User name is missing	Target user email not provided
107003	Self node sharing not allowed	Primary and secondary user are the same
107005	Some nodes do not belong to user	User is not the primary owner of all listed nodes
107007	User does not exist for sharing	Target user not found in the system
107014	Nodes shared via groups cannot be removed	Unshare via group management, not direct node removal
107022	User must be primary owner	Only primary owners can initiate sharing

---

CloudWatch Log Groups Reference

Log Group	When to Use
/aws/lambda/esp-LambdaUserNodeMapping	Device published MQTT mapping message — check here to see if it reached the cloud
/aws/lambda/esp-UserNodeMapping	App called the mapping API — check here to see the API-side result
/aws/lambda/esp-UserNodeSharing	Node sharing operations
/aws/lambda/esp-UserNodeSharingRequests	Sharing request accept/decline
/aws/lambda/esp-UserNodeMappingChallengeResponse	Challenge-response based mapping
/aws/lambda/esp-ConnectionNode	Node MQTT connect/disconnect events